home *** CD-ROM | disk | FTP | other *** search
- ------------------------------------------------------------------------------
-
- Initialization routine
- ----------------------
-
- Declaration:
-
- short pascal far PVOICE_INIT(void)
-
-
- This must be called once before any of the other routines are called. It hooks
- the interrupt service routine into the timer tick interrupt vector.
-
-
- Return value Meaning
- ------------ -------
- 0 success
- 1 voice package already initialized
- 2 wrong CPU, won't run on 8088 or 8086
-
- NOTE: PVOICE_INIT installs a Control-Break (Int 23h) handler which makes sure
- that the 8253 timer chip and the timer tick vector are restored to
- their original state before program termination. If your program
- installs its own Int 23h handler, then (a) It should be done after
- the call to PVOICE_INIT, and (b) It must call PVOICE_CBREAK before it
- allows the program to terminate. Failure to do this will result in
- a system crash.
-
-
- ------------------------------------------------------------------------------
-
- Cleanup routine
- ---------------
-
- Declaration:
-
- short pascal far PVOICE_CLEANUP(void)
-
-
- This restores the timer tick interrupt vector to its previous state. This
- routine must be called before the main program exits to DOS, unless the main
- program is memory-resident.
-
-
- Return value Meaning
- ------------ -------
- 0 success
- 1 voice package was not in the initialized state
-
-
- ------------------------------------------------------------------------------
-
- Start routine
- -------------
-
- Declaration:
-
- short pascal far PVOICE_START(blockaddr,blocklen,
- fileread,handle,datalen,startpos)
- unsigned char far *blockaddr;
- long blocklen;
- unsigned short fileread;
- unsigned short handle;
- long datalen;
- long startpos;
-
-
- This call initiates a voice output operation. It returns to the caller
- immediately. Voice output will continue asynchronously (background).
-
-
- Parameter Size Description
- --------- ---- -----------
- blockaddr 4 A far pointer to the memory block used for voice data.
- blocklen 4 A dword indicating the length of the memory block.
- fileread 2 A flag word. If this is 1, then data will be read from
- a file. If it is 0, then the data is assumed to be
- already present in the memory block.
- handle 2 An open file handle. This is ignored if the flag word
- is 0.
- datalen 4 A dword indicating the number of bytes of voice data
- to be played. If the flag word is 0, then this number
- must not be greater than the length of the memory
- block.
- startpos 4 A dword indicating the offset within the memory block
- where playback is to begin. This value must be less
- than blocklen.
-
- Return value Meaning
- ------------ -------
- 0 success
- 1 data length greater than block size but no file read
- 2 block size is too small (datalength > blocksize and
- blocklen < 8192 and file read = yes)
- 3 unable to read from file
- 4 voice playback is already in progress
- 5 startpos is not less than blocklen
-
-
- ------------------------------------------------------------------------------
-
- Catch-up routine
- ----------------
-
- Declaration:
-
- short pascal far PVOICE_CATCHUP(void)
-
-
- This must be called frequently from the main program if file reading is being
- used and the length of the data to be played is longer than the length of the
- memory block. The routine checks the progress of the address pointer in use
- by the interrupt service routine and fills in more data from the file if
- necessary.
-
-
- Return value Meaning
- ------------ -------
- 0 success
- 1 error while reading file
-
-
- ------------------------------------------------------------------------------
-
- Stop routine
- ------------
-
- Declaration:
-
- void pascal far PVOICE_STOP(void)
-
-
- Calling this will terminate the voice output operations immediately, before
- the end of output would have normally occurred. It is not necessary to call
- this routine unless it is desired to terminate voice output before the
- specified number of data bytes have been played.
-
-
- ------------------------------------------------------------------------------
-
- Status routine
- --------------
-
- Declaration:
-
- short pascal far PVOICE_STATUS(pcount,pindex)
- long far *pcount;
- long far *pindex;
-
-
- This will report the status of voice operations, including whether the
- output operation has completed, whether all the necessary data has been
- read from the file, and the current count of data bytes played.
-
-
- The first parameter is a far pointer to a dword which will receive the number
- of bytes which have already been output to the speaker.
-
- The second parameter is a far pointer to a dword which will receive the
- offset within the memory block of the next byte of data to be played.
-
-
- The return value is a flag word in which the lowest two bits are
- significant:
-
- Bit # Meaning if 1
- ----- ------------
- 0 playback is still in progress
- 1 unread data remains in file
-
-
-